Comissionamento

O comissionamento é o processo de ativação do terminal junto aos servidores de pagamento do BTG. Durante a execução, o terminal realiza a troca de certificados com os servidores remotos, estabelecendo um canal de comunicação seguro entre ambos.

Esses certificados são necessários para toda operação do SDK que dependa de comunicação remota. Sem eles, o terminal não consegue se comunicar com os servidores, e as operações que exigem essa comunicação falharão.

O comissionamento é persistente: uma vez realizado, o terminal permanece ativado até que seja descomissionado ou restaurado às configurações de fábrica.

Pré-requisito

O comissionamento exige que o BtgPayClient esteja conectado ao serviço BTG Pay. O processo de conexão está descrito na Configuração.

Verificando o estado

Antes de iniciar o comissionamento, é possível verificar se o terminal já foi ativado. O método isCommissioned() retorna true se o terminal já possui os certificados necessários, e false caso contrário.

if (client.isCommissioned()) {
    // O terminal já está comissionado.
} else {
    // Necessário executar o comissionamento.
}

Se o client não estiver conectado, isCommissioned() retorna false.

É recomendável verificar o estado na inicialização do app, para tratar cenários em que o terminal foi restaurado às configurações de fábrica entre execuções.

Executando o comissionamento

O comissionamento é iniciado com startCommissioning, que recebe o CNPJ do estabelecimento, o código de ativação e um CommissioningListener para receber o resultado.

O CNPJ e o código de ativação são fornecidos pelo BTG ao parceiro durante o processo de onboarding. Em caso de dúvida sobre esses valores, o canal de suporte técnico do BTG é o ponto de contato.

client.startCommissioning(
    cnpj = "30306294000145",
    activationCode = "ABC12345",
    listener = object : BtgPayClient.CommissioningListener {
        override fun onSuccess() {
            runOnUiThread {
                Log.i(TAG, "Terminal comissionado")
            }
        }
        override fun onError(message: String) {
            runOnUiThread {
                Log.e(TAG, "Comissionamento falhou: $message")
            }
        }
    }
)

O resultado chega exclusivamente pelo CommissioningListener: onSuccess indica que os certificados foram instalados, e onError traz a mensagem descrevendo o motivo da falha.

Os callbacks são invocados na Binder thread. Operações de UI dentro de onSuccess ou onError devem ser despachadas para a main thread, como demonstrado acima com runOnUiThread.

Tratamento de erros

A tabela abaixo lista os cenários de erro tratáveis no lado do client. Erros de validação — como CNPJ inválido ou código de ativação expirado — são processados pelo servidor e chegam como mensagem descritiva dentro de onError. O conteúdo e o formato dessas mensagens são definidos pelo servidor, não pelo client.

Cenário	Comportamento
Client não conectado	onError com "Not connected to BTG Pay service" — a chamada nem chega ao serviço
Falha na comunicação com o serviço	onError com a mensagem da exceção remota
Erro de validação do servidor	onError com a mensagem retornada pelo servidor

Exemplo completo

O exemplo abaixo demonstra o fluxo completo: conexão, verificação do estado e execução do comissionamento.

class ComissionamentoActivity : AppCompatActivity() {

    private val client by lazy { BtgPayClient(applicationContext) }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        client.connect(object : BtgPayClient.ConnectionListener {
            override fun onConnected() {
                if (client.isCommissioned()) {
                    Log.i(TAG, "Terminal já comissionado")
                    return
                }
                iniciarComissionamento()
            }
            override fun onDisconnected() {
                Log.w(TAG, "Serviço desconectado — aguardando reconexão")
            }
            override fun onBindFailed() {
                Log.e(TAG, "Serviço BTG Pay não instalado")
            }
            override fun onInitFailed(reason: String) {
                Log.e(TAG, "Falha na inicialização: $reason")
            }
        })
    }

    private fun iniciarComissionamento() {
        client.startCommissioning(
            cnpj = "30306294000145",
            activationCode = "ABC12345",
            listener = object : BtgPayClient.CommissioningListener {
                override fun onSuccess() {
                    runOnUiThread {
                        Log.i(TAG, "Comissionamento concluído")
                    }
                }
                override fun onError(message: String) {
                    runOnUiThread {
                        Log.e(TAG, "Comissionamento falhou: $message")
                    }
                }
            }
        )
    }

    override fun onDestroy() {
        client.disconnect()
        super.onDestroy()
    }
}